home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / criterr.com / READ.ME < prev   
Encoding:
Text File  |  1991-02-17  |  8.5 KB  |  197 lines
  1.  
  2.  
  3.                 CRITICAL ERROR HANDLER
  4.               A WAY TO AVOID THE DREADED
  5.        ABORT, RETRY, IGNORE, FAIL MESSAGE FROM WITHIN C PROGRAMS
  6.  
  7.  
  8. BY:    PETER HYMAN
  9.     148 Tennyson Drive
  10.     Plainsboro, NJ  08536
  11.     (609) 799-2638
  12.  
  13. JANUARY 1991
  14. with modifications 2/16/91
  15.  
  16. PURPOSE:  Some C Compilers offer a critical error trap, such as the former
  17. Lattice compiler.  Others have no elegant way to do so, and if there is a
  18. critical error, you get the familiar Abort, Retry, Ignore, Fail message to
  19. mess up your screen display.  CRITERR.ASM was designed to hook the INT 24H
  20. vector and allow for a graceful return from such an error while providing
  21. the programmer with complete information about the error.
  22.  
  23. FILES:    The following files are included.
  24.  
  25.     CETEST.C    ; TEST C FILE TO DEMONSTRATE CRITERR USAGE
  26.     CRITERR.ASM    ; ASSEMBLER SOURCE FILE FOR ALTERNATE CRITICAL
  27.             ; ERROR HANDLER
  28.     CRITERR.H    ; HEADER FILE CONTAINING STRUCTURE DEFINITIONS AND
  29.             ; CHARACTER ARRAYS TO PRINT OUT ERRORS
  30.         CRITERR.LST     ; LISTING FILE FOR ASM MODULE
  31.  
  32. COMPILATION STEPS:  The assmebler file uses simplified segment directives
  33. and no separate macro include file.  I have tested it with both the Microsoft
  34. and Turbo assemblers.  Assemble with the following command line switches
  35.  
  36. MSC:    masm /mx /dI8086[s|c|m|l] criterr;
  37. TURBO:    tasm /mx /dI8086[s|c|m|l] /q criterr
  38.     The /q option will yield a much smaller object module
  39. The [s|c|m|l] are individual model designators, Small, Compact, Medium or 
  40. Large.
  41.  
  42. To compile the C test file, simply specify the memory model and other options
  43. you may want.  I use the Zortech C++ compiler, and it requires no additional
  44. command line switches other than the memory or debug options.
  45.  
  46. ztc -m[s|c|m|l] [-g] cetest [criterr.obj|criterr.asm]
  47.  
  48. where [s|c|m|l] is the individual memory model, [-g] would be for the 
  49. debugger, [criterr.obj] would be to link in the object module created for 
  50. the alternate critical error handler, and/or [criterr.asm] would be if you 
  51. wanted Zortech to call MASM for you (saving the step above).
  52.  
  53. You may also want to add criterr to your library after testing.
  54.  
  55. !!!!! THIS PROGRAM HAS NOT BEEN TESTED ON OS/2 OR WITH C++ !!!!!
  56.  
  57. USAGE:    There are two functions in the CRITERR.ASM module.
  58.  
  59.     CRITERR( ONOFF )
  60.     CLRCRITERR( )
  61.  
  62. int    criterr( onoff )
  63.     int onoff;    1 = turn on critical error trap, 0 = remove
  64.  
  65.     returns: 0 = installed, 1 = already installed
  66.  
  67.     if the handler has already been installed and you try to turn it on
  68.     again, it will return a 1, otherwise, it will return a 0.
  69.  
  70. void    clrcriterr( void )
  71.     fills structure with NULLs
  72.  
  73. After DOS operations, the structure member cerr.ceflag will contain a 1 if
  74. there was a critical error.  If not, check your compiler's system
  75. error variable (usually errno or oserr).  If there was a critical error,
  76. complete diagnostic information is stored in the cerr structure (see
  77. criterr.h).
  78.  
  79. If the error type was a disk error, the structure member cerr.drive will
  80. contain a character letter corresponding to the drive the error occured on
  81. (i.e. A,B,C ).  If not, the error was probably a printer or other error, and
  82. you can read a device name for the character device header block in the
  83. structure member cerr.name.  For DOS versions 3 and up, extended error
  84. information is also included in the structure members cerr.exterr, cerr.eclass,
  85. cerr.locus and cerr.action.
  86.  
  87. Once the error type has been determined, several arrays of character strings
  88. can be referenced to get English translations of the error (see criterr.h).
  89.  
  90. !!!!! IMPORTANT !!!!!
  91. THERE IS NO AUTOMATIC RESET OF THE CERR STRUCTURE.  THE RESULTS ARE STICKY, AND
  92. UNLESS EXPLICITLY CLEARED, WILL REMAIN SET UNTIL THE NEXT CRITICAL ERROR.
  93. THEREFORE, THE FUNCTION clrcriterr() MUST BE CALLED AFTER THE ERROR HAS BEEN
  94. EVALUATED.  IF CRITERR( 0 ) IS CALLED, THE STRUCTURE IS CLEARED.
  95.  
  96. ALSO, THE LOGIC OF THIS HANDLER IS THAT IT WILL AUTOMATICALLY RETURN AN IGNORE
  97. OR FAIL CODE TO DOS TO RESTORE THE MACHINE TO A STABLE STATUS.  THERE IS NO
  98. NEED TO PROMPT THE USER FOR ABORT, RETRY, ETC.  YOU MAY SIMPLY SAY, PRINTER
  99. ERROR, OR DISK ERROR, CONTINUE?, OR PRINT THE ASSOCIATED ERROR MESSAGES IN
  100. CRITERR.H.  IT'S MUCH CLEANER THIS WAY.
  101.  
  102. Comments, Feedback?  Please let me know your experience with this program and
  103. suggest any improvements, modification or corrections.
  104.  
  105. You may wish to refer to a DOS Technical Reference Manual or other DOS Book
  106. for more information about how this handler works.
  107.  
  108.  
  109.  
  110. 2/16/91:
  111.  
  112. Several changes were made.  
  113.  
  114. The cerr structure was modified (see the criterr.h file).  A new member 
  115. ceflag was added to be used as a notification that a critical error 
  116. occured.  This was because a critical error number of 0 is used to 
  117. indicate a write protect error.  Rather than change the numbering to be 1 
  118. indexed, I just set the flag.
  119.  
  120. The external function _dos_exterr is no longer called.  The reason is that 
  121. the exterr is now byte length, and _dos_exterr expects a word.  The 
  122. program now calls int 59h directly.
  123.  
  124. The code which set the read_wr member was moved.  There was a bug which 
  125. would leave it unset if a write error occured to a character device such 
  126. as a printer.  This would indicate a reading error, which is impossible.
  127. (see .asm source below the reponse: label).
  128.  
  129. The method in which the program determined if the critical error handler 
  130. was already installed was faulty.  It never tested if it was already 
  131. installed if you passed criterr(1).  It would reinstall it and would cause 
  132. you to lose the address of the original INT 24h handler.  This means that 
  133. the alternate handler would never be uninstalled until the C program was 
  134. exited.  See code below removetrap: and settrap: labels in the .asm 
  135. source.
  136.  
  137. Some small descriptive changes were made to the .h file.  Also the cerr. 
  138. structure was changed.  Three new descriptive string arrays were added for
  139. showing Reading or Writing errors, Area of Disk in which an error occured,
  140. and for displaying allowable responses (see cetest.c).
  141.  
  142. One additional note.  The clrcriterr() function need not be called if you 
  143. are just turning off the critical error handler.  When you call criterr(0) 
  144. if will clear the structure for you.  It also initializes it when you turn 
  145. it on.  You only need to call clrcriterr() directly if the handler remains 
  146. installed during program execution and a critical error has been observed.
  147.  
  148. More feedback?  I hope so.
  149.  
  150.  
  151.          ----------------end-of-author's-documentation---------------
  152.  
  153.                          Software Library Information:
  154.  
  155.                     This disk copy provided as a service of
  156.  
  157.                            Public (software) Library
  158.  
  159.          We are not the authors of this program, nor are we associated
  160.          with the author in any way other than as a distributor of the
  161.          program in accordance with the author's terms of distribution.
  162.  
  163.          Please direct shareware payments and specific questions about
  164.          this program to the author of the program, whose name appears
  165.          elsewhere in  this documentation. If you have trouble getting
  166.          in touch with the author,  we will do whatever we can to help
  167.          you with your questions. All programs have been tested and do
  168.          run.  To report problems,  please use the form that is in the
  169.          file PROBLEM.DOC on many of our disks or in other written for-
  170.          mat with screen printouts, if possible.  PsL cannot debug pro-
  171.          programs over the telephone, though we can answer questions.
  172.  
  173.          Disks in the PsL are updated  monthly,  so if you did not get
  174.          this disk directly from the PsL, you should be aware that the
  175.          files in this set may no longer be the current versions. Also,
  176.          if you got this disk from another vendor and are having prob-
  177.          lems,  be aware that  some files may have become corrupted or
  178.          lost by that vendor. Get a current, working disk from PsL.
  179.  
  180.          For a copy of the latest monthly software library newsletter
  181.          and a list of the 3,000+ disks in the library, call or write
  182.  
  183.                            Public (software) Library
  184.                                P.O.Box 35705 - F
  185.                             Houston, TX 77235-5705
  186.  
  187.                                 1-800-2424-PSL
  188.                              MC/Visa/AmEx/Discover
  189.  
  190.                           Outside of U.S. or in Texas
  191.                           or for general information,
  192.                               Call 1-713-524-6394
  193.  
  194.                           PsL also has an outstanding
  195.                           catalog for the Macintosh.
  196.  
  197.